package com.studiofortress.sf.graphics.display;

/**
 * Controls class contains methods for accessing input.
 * 
 * This class is not meant to be initialised. Instead you can
 * get the Control object from the window you want to interact
 * with, through the 'getControls' method of the Graphics class.
 * 
 * The x and y position of the mouse, relate to it's position
 * in the window. The mouse z position is the position of the
 * mouse wheel.
 * 
 * The mouse buttons can be detected as being down using
 * the 'isMouseDown' method. The integer it requres related to
 * 'MOUSE_LEFT', 'MOUSE_RIGHT' and 'MOUSE_MIDDLE' which correspond
 * to the three mouse buttons.
 * 
 * Keyboard presses can be detected using the 'isKeyDown' method.
 * It will return true or false if the given key is found.
 * 
 * Names include:
 * 'A', 'B', 'C',.. 'Z' for the alphabet.
 * '1', '2', '3',.. '0' for the numbers.
 * 'F1', 'F2', 'F3', etc for the F-keys.
 * 'Left', 'Right', 'Up' and 'Down' for the arrow keys.
 * 'Home', 'Escape', 'Enter', 'Space' and others also
 * relate to their corresponding keys.
 * 
 * Incrrect key names will always return false.
 * Key names must start capitalize, such as 'Home' instead of 'home'.
 * 
 * Note: Key names are from KeyEvent from the Java API.
 * http://java.sun.com/javase/6/docs/api/java/awt/event/KeyEvent.html
 * 
 * @author Joseph Lenton - JosephLenton@StudioFortress.com
 * @version 13/05/07
 */
public interface Controls
{
    // represents mouse buttons
    public static final int MOUSE_LEFT = 0;
    public static final int MOUSE_RIGHT = 1;
    public static final int MOUSE_MIDDLE = 2;
    
    /**
     * Returns the last known X position
     * of the mouse.
     * @return the mouse Y position.
     */
    public int getMouseX();
    
    /**
     * Returns the last known Y position
     * of the mouse.
     * @return the mouse Y position.
     */
    public int getMouseY();
    
    /**
     * Returns the last known position
     * of the mouse wheel.
     * @return the current position of the mouse wheel.
     */
    public int getMouseZ();
    
    /**
     * Returns true if the mouse button is currently being pressed. False if
     * not.
     * @param mouseButton the mouse button you are checking. (MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE).
     * @return true if the button is being pressed, false if not.
     */
    public boolean isMouseDown(int mouseButton);

    /**
     * Returns true if there was a mouse click during the last frame. Note that
     * regardless of if this is checked or not, it will be cleared after this
     * frame.
     *
     * A click is regarded to be the moment the mouse went down.
     * 
     * @param mouseButton The button to check the mouse click of. (MOUSE_LEFT, MOUSE_RIGHT or MOUSE_MIDDLE).
     * @return true if the button did click, otherwise false.
     */
    public boolean isMouseClick(int mouseButton);

    /**
     * Checks if any mouse button is currently pressed down. This only includes
     * the mouse buttons that can be checked through isMouseDown.
     * @return True if any mouse button is currently pressed, false if not.
     */
    public boolean isAnyMouseDown();

    /**
     * Returns true if the given string representation
     * of a key, is being pressed. False if not.
     * 
     * Example keys: 'A', 'B', 'Right', 'Home', 'Escape', 'F1'.
     * 
     * See above for a thorough description.
     * Incrrect key names will always return false.
     * @param key a string representing the key to be checked.
     * @return true if the key is being pressed, false if not.
     */
    public boolean isKeyDown(String key);

    /**
     * Returns true if the given key has been pressed. The key should be a
     * KeyEvent key code.
     *
     * @param keyCode The KeyEvent code for the key to check for.
     * @return True if the key is pressed, otherwise false if not.
     */
    public boolean isKeyDown(int keyCode);

    /**
     * @return True if any key on the keyboard is currently pressed, otherwise false.
     */
    public boolean isAnyKeyDown();
}